home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / radiobutton.n < prev    next >
Text File  |  1994-09-20  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4. radiobutton(n)             Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      radiobutton - Create and manipulate radio-button widgets
  12.  
  13. SYNOPSIS
  14.      radiobutton _p_a_t_h_N_a_m_e ?_o_p_t_i_o_n_s?
  15.  
  16. STANDARD OPTIONS
  17.      activeBackground               bitmap          fontrelief     |
  18.      activeForeground               borderWidth     foregroundtext |
  19.      anchor          cursor         padX            textVariable   |
  20.      background      disabledForeground             padX           |
  21.  
  22.      See the ``options'' manual entry for details on the standard
  23.      options.
  24.  
  25. WIDGET-SPECIFIC OPTIONS
  26.      Name:           command
  27.      Class:          Command
  28.      Command-Line Switch:-command
  29.  
  30.           Specifies a Tcl command to associate with  the  button.
  31.           This  command  is typically invoked when mouse button 1
  32.           is released over the button window.  The button's  glo-
  33.           bal  variable (-variable option) will be updated before
  34.           the command is invoked.
  35.  
  36.      Name:           height                                        |
  37.      Class:          Height                                        |
  38.      Command-Line Switch:-height                                   |
  39.  
  40.                                                                         ||
  41.           Specifies a desired height for the button.  If a bitmap  |
  42.           is being displayed in the button then the value  is  in  |
  43.           screen  units  (i.e.  any  of  the  forms acceptable to  |
  44.           Tk_GetPixels); for text it is in  lines  of  text.   If  |
  45.           this  option  isn't  specified,  the  button's  desired  |
  46.           height is computed from the size of the bitmap or  text  |
  47.           being displayed in it.
  48.  
  49.      Name:           selector
  50.      Class:          Foreground
  51.      Command-Line Switch:-selector
  52.  
  53.           Specifies the color to draw in the selector  when  this
  54.           button  is  selected.   If specified as an empty string  |
  55.           then no selector is drawn for the button.                |
  56.  
  57.      Name:           state                                         |
  58.      Class:          State                                         |
  59.      Command-Line Switch:-state                                    |
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. radiobutton(n)             Tk Commands
  71.  
  72.  
  73.  
  74.                                                                         ||
  75.           Specifies  one  of  three  states for the radio button:  |
  76.           normal, active, or disabled.  In normal state the radio  |
  77.           button is displayed using the foreground and background  |
  78.           options.  The active state is typically used  when  the  |
  79.           pointer  is over the radio button.  In active state the  |
  80.           radio button is displayed  using  the  activeForeground  |
  81.           and  activeBackground  options.   Disabled  state means  |
  82.           that the  radio  button  is  insensitive:   it  doesn't  |
  83.           activate  and  doesn't respond to mouse button presses.  |
  84.           In this state  the  disabledForeground  and  background  |
  85.           options determine how the radio button is displayed.
  86.  
  87.      Name:           value
  88.      Class:          Value
  89.      Command-Line Switch:-value
  90.  
  91.           Specifies value to store  in  the  button's  associated
  92.           variable whenever this button is selected.  Defaults to
  93.           the name of the radio button.
  94.  
  95.      Name:           variable
  96.      Class:          Variable
  97.      Command-Line Switch:-variable
  98.  
  99.           Specifies name of global variable to set whenever  this
  100.           button  is  selected.   Changes  in  this variable also
  101.           cause  the  button  to  select  or   deselect   itself.
  102.           Defaults to the value selectedButton.
  103.  
  104.      Name:           width                                         |
  105.      Class:          Width                                         |
  106.      Command-Line Switch:-width                                    |
  107.  
  108.                                                                         ||
  109.           Specifies  a desired width for the button.  If a bitmap  |
  110.           is being displayed in the button then the value  is  in  |
  111.           screen  units  (i.e.  any  of  the  forms acceptable to  |
  112.           Tk_GetPixels); for text it is in characters.   If  this  |
  113.           option  isn't  specified, the button's desired width is  |
  114.           computed from the size of  the  bitmap  or  text  being  |
  115.           displayed in it.
  116. _________________________________________________________________
  117.  
  118.  
  119. DESCRIPTION
  120.      The radiobutton command creates a new window (given  by  the
  121.      _p_a_t_h_N_a_m_e  argument)  and makes it into a radiobutton widget.
  122.      Additional options, described above, may be specified on the
  123.      command  line or in the option database to configure aspects
  124.      of the radio button such as its colors, font, text, and ini-
  125.      tial  relief.   The radiobutton command returns its _p_a_t_h_N_a_m_e
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. radiobutton(n)             Tk Commands
  137.  
  138.  
  139.  
  140.      argument.  At the time this command is invoked,  there  must
  141.      not  exist  a  window  named _p_a_t_h_N_a_m_e, but _p_a_t_h_N_a_m_e's parent
  142.      must exist.
  143.  
  144.      A radio button is a widget that displays a textual string or  |
  145.      bitmap  and a diamond called a _s_e_l_e_c_t_o_r.  A radio button has  |
  146.      all of the behavior of  a  simple  button:  it  can  display  |
  147.      itself  in  either of three different ways, according to the  |
  148.      state option; it can be made to appear  raised,  sunken,  or
  149.      flat;  it can be made to flash; and it invokes a Tcl command
  150.      whenever mouse button 1 is clicked over the check button.
  151.  
  152.      In addition, radio buttons can be _s_e_l_e_c_t_e_d.  If a radio but-
  153.      ton  is  selected  then  a  special highlight appears in the
  154.      selector and a Tcl variable associated with the radio button
  155.      is  set  to  a particular value.  If the radio button is not
  156.      selected then the selector is drawn in a different  fashion.
  157.      Typically, several radio buttons share a single variable and
  158.      the value of the variable indicates which radio button is to
  159.      be  selected.   When  a radio button is selected it sets the  |
  160.      value of the variable to indicate  that  fact;   each  radio  |
  161.      button also monitors the value of the variable and automati-  |
  162.      cally selects and deselects itself when the variable's value  |
  163.      changes.   By  default  the variable selectedButton is used;
  164.      its contents give the name of the button that  is  selected,
  165.      or  the empty string if no button associated with that vari-
  166.      able is selected.  The name of the variable for a radio but-
  167.      ton, plus the variable to be stored into it, may be modified
  168.      with options on the command line or in the option  database.
  169.      By  default a radio button is configured to select itself on
  170.      button clicks.
  171.  
  172.  
  173. WIDGET COMMAND
  174.      The radiobutton command creates a new Tcl command whose name
  175.      is  _p_a_t_h_N_a_m_e.   This  command  may be used to invoke various
  176.      operations on the widget.   It  has  the  following  general
  177.      form:
  178.  
  179.           _p_a_t_h_N_a_m_e _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  180.  
  181.      _O_p_t_i_o_n and the _a_r_gs determine the exact behavior of the com-
  182.      mand.   The following commands are possible for radio-button
  183.      widgets:
  184.  
  185.      _p_a_t_h_N_a_m_e activate
  186.           Change the radio button's state to active and redisplay
  187.           the  button  using its active foreground and background
  188.           colors instead  of  normal  colors.   This  command  is  |
  189.           ignored  if the radio button's state is disabled.  This  |
  190.           command is obsolete and will eventually be removed; use  |
  191.           ``_p_a_t_h_N_a_m_e configure -state active'' instead.            |
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. radiobutton(n)             Tk Commands
  203.  
  204.  
  205.  
  206.      _p_a_t_h_N_a_m_e configure ?_o_p_t_i_o_n? ?_v_a_l_u_e _o_p_t_i_o_n _v_a_l_u_e ...?               ||
  207.           Query  or  modify  the  configuration  options  of  the  |
  208.           widget.  If no _o_p_t_i_o_n  is  specified,  returns  a  list  |
  209.           describing  all  of  the available options for _p_a_t_h_N_a_m_e  |
  210.           (see Tk_ConfigureInfo for information on the format  of  |
  211.           this list).  If _o_p_t_i_o_n is specified with no _v_a_l_u_e, then  |
  212.           the command returns a list  describing  the  one  named  |
  213.           option  (this list will be identical to the correspond-  |
  214.           ing sublist of the  value  returned  if  no  _o_p_t_i_o_n  is  |
  215.           specified).   If  one  or  more  _o_p_t_i_o_n-_v_a_l_u_e pairs are  |
  216.           specified, then the command modifies the  given  widget  |
  217.           option(s) to have the given value(s);  in this case the  |
  218.           command returns an empty string.  _O_p_t_i_o_n may  have  any  |
  219.           of the values accepted by the radiobutton command.       |
  220.  
  221.      _p_a_t_h_N_a_m_e deactivate                                                ||
  222.           Change the radio button's state to normal and redisplay  |
  223.           the button using its normal foreground  and  background  |
  224.           colors.   This command is ignored if the radio button's  |
  225.           state is disabled.  This command is obsolete  and  will  |
  226.           eventually  be removed; use ``_p_a_t_h_N_a_m_e configure -state  |
  227.           normal'' instead.
  228.  
  229.      _p_a_t_h_N_a_m_e deselect
  230.           Deselect the radio  button:   redisplay  it  without  a
  231.           highlight  in the selector and set the associated vari-
  232.           able to an empty string.  If this radio button was  not
  233.           currently selected, then the command has no effect.
  234.  
  235.      _p_a_t_h_N_a_m_e flash
  236.           Flash  the  radio  button.   This  is  accomplished  by
  237.           redisplaying  the radio button several times, alternat-
  238.           ing between active and normal colors.  At  the  end  of
  239.           the  flash  the  radio  button  is  left  in  the  same
  240.           normal/active state as when the  command  was  invoked.  |
  241.           This  command is ignored if the radio button's state is  |
  242.           disabled.
  243.  
  244.      _p_a_t_h_N_a_m_e invoke
  245.           Does just what would have happened if the user  invoked  |
  246.           the  radio button with the mouse: select the button and  |
  247.           invoke its associated Tcl command,  if  there  is  one.  |
  248.           The  return value is the return value from the Tcl com-  |
  249.           mand, or an empty string if there is no command associ-  |
  250.           ated with the radio button.  This command is ignored if  |
  251.           the radio button's state is disabled.
  252.  
  253.      _p_a_t_h_N_a_m_e select
  254.           Select the radio button:  display it with a highlighted
  255.           selector  and  set the associated variable to the value
  256.           corresponding to this widget.
  257.  
  258.  
  259.  
  260.  
  261. Tk                                                              4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. radiobutton(n)             Tk Commands
  269.  
  270.  
  271.  
  272. BINDINGS
  273.      Tk automatically creates class bindings  for  radio  buttons  |
  274.      that give them the following default behavior:                |
  275.  
  276.      [1]                                                                ||
  277.           The  radio  button  activates whenever the mouse passes  |
  278.           over it and deactivates whenever the mouse  leaves  the  |
  279.           radio button.                                            |
  280.  
  281.      [2]                                                                ||
  282.           The radio button's relief is changed to sunken whenever  |
  283.           mouse button 1 is pressed over it, and  the  relief  is  |
  284.           restored  to  its original value when button 1 is later  |
  285.           released.                                                |
  286.  
  287.      [3]                                                                ||
  288.           If  mouse button 1 is pressed over the radio button and  |
  289.           later released over the radio button, the radio  button  |
  290.           is invoked (i.e. it is selected and the command associ-  |
  291.           ated with the button is  invoked,  if  there  is  one).  |
  292.           However, if the mouse is not over the radio button when  |
  293.           button 1 is released, then no invocation occurs.         |
  294.  
  295.      The behavior of radio buttons can be changed by defining new  |
  296.      bindings  for  individual widgets or by redefining the class  |
  297.      bindings.
  298.  
  299.  
  300. KEYWORDS
  301.      radio button, widget
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Tk                                                              5
  328.  
  329.  
  330.  
  331.